3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Sets

A set object (or, more briefly, a set) is a collection of zero or more elements, each of which has both an element type and some associated element data. QuickDraw 3D provides routines that you can use to create a new set, get the type of a set, add elements to a set, get the data associated with an element in a set, loop through all the elements in a set, and perform other operations on sets.

In general, you'll use the routines described in this section to handle sets containing elements with custom element types. You should use other QuickDraw 3D routines to handle sets that consist solely of elements with predefined element types. For example, to create a set of vertex attributes, you can use the Q3VertexAttributeSet_New function (to create a new empty set of vertex attributes) and the Q3AttributeSet_Add function (to add elements to that set). See the chapter "Attribute Objects" for information on managing attribute sets. See the section "Defining Custom Elements" for information on handling custom element types.

Q3Set_New

You can use the Q3Set_New function to create a new set.



 
TQ3SetObject Q3Set_New (void);

DESCRIPTION

The Q3Set_New function returns, as its function result, a new set object. The set is initially empty. If Q3Set_New cannot create a new set object, it returns NULL .

Q3Set_GetType

You can use the Q3Set_GetType function to get the type of a set.



 
TQ3ObjectType Q3Set_GetType (TQ3SetObject set);

set: A set object.

DESCRIPTION

The Q3Set_GetType function returns, as its function result, the type of the set specified by the set parameter. The type of set currently supported by QuickDraw 3D is defined by the constant:



 
kQ3SetTypeAttribute

If the type of the set cannot be determined or is invalid, Q3Set_GetType returns the value kQ3ObjectTypeInvalid .

Q3Set_Add

You can use the Q3Set_Add function to add an element to a set.



 
TQ3Status Q3Set_Add (

                     TQ3SetObject set, 

                     TQ3ElementType type, 

                     const void *data);

set: A set object.
type: An element type.
data: A pointer to the element's data.

DESCRIPTION

The Q3Set_Add function adds the element specified by the type and data parameters to the set specified by the set parameter. The set must already exist when you call Q3Set_Add . Note that the element data is copied into the set. Accordingly, you can reuse the data parameter once you have called Q3Set_Add .

If the specified element type is a custom element type, Q3Set_Add uses the custom type's kQ3MethodTypeElementCopyAdd or kQ3MethodTypeElementCopyReplace custom methods. See the chapter "QuickDraw 3D Objects" for complete information on custom element types.

Q3Set_Get

You can use the Q3Set_Get function to get the data associated with an element in a set.



 
TQ3Status Q3Set_Get (TQ3SetObject set, TQ3ElementType type, void *data);

set: A set object.
type: An element type.
data: On entry, a pointer to a structure large enough to hold the data associated with elements of the specified type. On exit, a pointer to the data of the element having the specified type.

DESCRIPTION

The Q3Set_Get function returns, in the data parameter, the data currently associated with the element whose type is specified by the type parameter in the set specified by the set parameter. If no element of that type is in the set, Q3Set_Get returns kQ3Failure .

If you pass the value NULL in the data parameter, no data is copied back to your application. (Passing NULL might be useful simply to determine whether a set contains a specific type of element.)

If the specified element type is a custom element type, Q3Set_Get uses the custom type's kQ3MethodTypeElementCopyGet custom method. See the chapter "QuickDraw 3D Objects" for complete information on custom element types.

Q3Set_Contains

You can use the Q3Set_Contains function to determine whether a set contains an element of a particular type.



 
TQ3Boolean Q3Set_Contains (TQ3SetObject set, TQ3ElementType type);

set: A set object.
type: An element type.

DESCRIPTION

The Q3Set_Contains function returns, as its function result, a Boolean value that indicates whether the set specified by the set parameter contains (kQ3True ) or does not contain (kQ3False ) an element of the type specified by the type parameter.

Q3Set_GetNextElementType

You can use the Q3Set_GetNextElementType function to iterate through the elements in a set.



 
TQ3Status Q3Set_GetNextElementType (

                     TQ3SetObject set, 

                     TQ3ElementType *type);

set: A set object.
type: On entry, an element type, or kQ3ElementTypeNone to get the first element type in the specified set. On exit, the element type that immediately follows the specified element type in the set, or kQ3ElementTypeNone if there are no more element types.

DESCRIPTION

The Q3Set_GetNextElementType function returns, in the type parameter, the type of the element that immediately follows the element having the type specified by the type parameter in the set specified by the set parameter. To get the type of the first element in the set, pass kQ3ElementTypeNone in the type parameter. Q3Set_GetNextElementType returns kQ3ElementTypeNone when it has reached the end of the list of elements.

Q3Set_Empty

You can use the Q3Set_Empty function to empty a set of all the elements it contains.



 
TQ3Status Q3Set_Empty (TQ3SetObject target);

target: A set object.

DESCRIPTION

The Q3Set_Empty function removes all the elements currently in the set specified by the target parameter.

If the specified element type is a custom element type, Q3Set_Empty uses the custom type's kQ3MethodTypeElementDelete custom method. See the chapter "QuickDraw 3D Objects" for complete information on custom element types.

Q3Set_Clear

You can use the Q3Set_Clear function to remove an element of a certain type from a set.



 
TQ3Status Q3Set_Clear (TQ3SetObject set, TQ3ElementType type);

set: A set object.
type: An element type.

DESCRIPTION

The Q3Set_Clear function removes the element whose type is specified by the type parameter from the set specified by the set parameter.

If the specified element type is a custom element type, Q3Set_Clear uses the custom type's kQ3MethodTypeElementDelete custom method. See the chapter "QuickDraw 3D Objects" for complete information on custom element types.